Skip to content

Conversation

@youngjungithub
Copy link
Contributor

@youngjungithub youngjungithub commented Mar 18, 2025

Ticket

  • Update sidebars.js with explicit category definitions
  • Modify how-to guides category description
  • Create reference/explanation category scaffolding
  • Align documentation structure with Diátaxis framework

- Update sidebars.js with explicit category definitions
- Modify how-to guides category description
- Create reference/explanation category scaffolding
- Align documentation structure with Diátaxis framework
@youngjungithub youngjungithub requested review from a team as code owners March 18, 2025 19:38
- Remove invalid documentation_type field from category configs
- Update category descriptions per Diátaxis framework
- Fix Tutorials/How-Tos/Reference/Explanation categories
- Align with Docusaurus schema requirements
@youngjungithub youngjungithub marked this pull request as draft March 18, 2025 19:48
@youngjungithub youngjungithub marked this pull request as ready for review March 18, 2025 19:49
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@youngjungithub This duplicates content between the how-to guide and explanation. I've heard our technical writers mention how this can increase the maintenance burden, because now we have to keep two copies of the same data in sync over time.

Is this intentional, or do you have any ideas on how we can duplicate only the essential information?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes it is intentional. To minimize maintenance burden we:

  1. Keep procedural steps in How-To Guides
  2. Store explanatory context in shared components
  3. Use cross-references instead of duplications

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

@youngjungithub youngjungithub Mar 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the plan I have:

parsing.json-strings file

## Implementation Steps

+ [Why this pattern works](/explanation/parsing-codec-chaining)

### 1. Chain decoders for type safety
- Existing code example -
```typescript
import * as t from 'io-ts';
import { nonEmptyArray, JsonFromString, NumberFromString } from 'io-ts-types';
import { httpRequest, optional } from '@api-ts/io-ts-http';

// Define the Filter type for the JSON string
const Filter = t.type({
  category: t.string,
  tags: t.array(t.string),
  price: t.type({
    min: t.number,
    max: t.number,
  }),
});...Example continues......

parsing-codec-chaining file

# Type Safety in I/O Decoding

I am going to ask Designers to draw up a codec chaining diagram and post it here.

## Design Rationale

Though we know headers, URL parameters, and query parameters will be received as a
`string` or `string[]` value, due to a limitation in api-ts..... Continue...
but need to decode it with a codec that can only decode a narrower type. This pattern is
called codec chaining.

## Tradeoffs
- **Pros**: Enables gradual type refinement

@ericcrosson-bitgo ericcrosson-bitgo merged commit bcda594 into master Mar 19, 2025
6 checks passed
@ericcrosson-bitgo ericcrosson-bitgo deleted the audit-docs branch March 19, 2025 16:46
@github-actions
Copy link

🎉 This PR is included in version @api-ts/typed-express-router@2.0.0-beta.1 🎉

The release is available on npm package (@beta dist-tag)

Your semantic-release bot 📦🚀

@github-actions
Copy link

🎉 This PR is included in version @api-ts/express-wrapper@2.0.0-beta.1 🎉

The release is available on npm package (@beta dist-tag)

Your semantic-release bot 📦🚀

@github-actions
Copy link

🎉 This PR is included in version @api-ts/typed-express-router@1.1.14 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

@github-actions
Copy link

🎉 This PR is included in version @api-ts/express-wrapper@1.0.34 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

@github-actions
Copy link

🎉 This PR is included in version @api-ts/superagent-wrapper@1.3.4 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

@github-actions
Copy link

🎉 This PR is included in version @api-ts/openapi-generator@5.8.0 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants